feat: oversampled PSF inversion wiring — mapping formalism (phase 2b) - #357

Summary

Oversampled PSF convolution, phase 2b (inversion wiring) of the feature designed in #353: pixelized reconstructions via the mapping formalism now convolve at the fine resolution when the dataset's PSF is oversampled. The mapper contributes a new sub-resolution mapping_matrix_over_sampled (one row per sub-pixel, no sub_fraction fold), which the phase-2a Convolver convolves on the fine grid and bins back — convolution now happens before the sub-pixel fold, as the physics requires. mapping.py itself needed no logic change: the PSF application site is the shared AbstractInversionImaging.operated_mapping_matrix_list, exactly as the approved design recorded.

Tracks #356. Builds on #355 (phase 2a).

API Changes

Additive; nothing changes while convolve_over_sample_size == 1.

• Mapper.mapping_matrix_over_sampled — sub-resolution mapping matrix, shape [total_sub_pixels, source_pixels] in per-pixel sub-block order (the 2a Convolver input format). Binning its rows by the mean of each sub-block reproduces mapping_matrix exactly (tested).
• AbstractInversionImaging routes every PSF-convolution site (operated_mapping_matrix_list, linear_func_operated_mapping_matrix_dict, mapper_operated_mapping_matrix_dict) through a single helper that picks the sub-resolution matrix for Mapper objects when the PSF is oversampled.
• Loud guards (InversionException) on the formalisms that consume psf.kernel.native at image resolution and are deferred per the design: linear-function objects without an operated override, the data_linear_func_matrix preload, and InversionImagingSparse.psf_weighted_data.
• MockPSF gains convolve_over_sample_size = 1 to match the real interface.

Test Plan

• mapping_matrix_over_sampled delta-kernel identity: mean-binned rows == mapping_matrix to 1e-14.
• End-to-end s=2: operated_mapping_matrix_list matches an independent brute-force fine-raster convolution + bin (plain loops, no shared indexing) to 1e-12.
• Guard tests: linear-func objects and the kernel-native preload raise under an oversampled PSF.
• Full suites against this branch: PyAutoArray / PyAutoGalaxy / PyAutoLens (counts in the issue sign-off).

Memory profile (design §4 risk)

Native FFT cube (ny·s, nx·s, n_src), fp64, for a realistic strong-lens case (fft frame 256² at s=1):

s=2 with ~1000 sources is ~2.1 GB (×4 the s=1 cube) plus FFT transients — fine on A100-class GPUs, tight on small (6 GB) cards. Oversampled inversion stays opt-in (nothing defaults on); chunked per-column convolution and/or use_mixed_precision are the mitigations if profiling shows pressure in practice.

Validation checklist (--auto run)

• Effective level: supervised (header: supervised, cap: feature → supervised)
• Plan: on the issue (feat: oversampled PSF inversion wiring — mapping formalism (phase 2b) #356), written at filing; design pre-approved in design: oversampled PSF convolution phase 1/4 — note + ground truth #353; predecessor feat: oversampled PSF convolution core API (convolve_over_sample_size) #355 merged
• Gate: tests full suites pass (counts on the issue) · smoke n/a (opt-in feature, no default-path change) · review CLEAN · Heart YELLOW (chronic set, human-driven session)
• Human: diff matches plan (no scope creep)?
• Human: merge, amend, or reject — then log the outcome

🤖 Generated with Claude Code